package com.joker.demo.core.executor;

import com.joker.demo.core.domain.dto.JobExecutorParamsDTO;
import com.joker.demo.core.domain.dto.JobExecutorResultDTO;

/**
 * 任务执行器服务接口
 * 
 * 这个接口定义了任务执行器的核心契约，用于执行具体的任务逻辑。
 * 实现此接口的类可以作为任务处理器，支持多线程执行任务。
 * 
 * 使用场景：
 * 1. 类级别的任务处理器：在类上添加@JobHandle注解，并实现此接口
 * 2. 复杂任务逻辑：当任务逻辑比较复杂时，可以实现此接口
 * 3. 需要状态管理的任务：实现类可以维护任务执行状态
 * 
 * 实现要求：
 * - execute方法应该处理具体的任务逻辑
 * - 方法应该是线程安全的
 * - 应该正确处理异常并返回适当的结果
 *
 * @author : feixiang.li
 * @since : 2025-07-24 14:11
 */
public interface JobExecutorService {

    /**
     * 执行任务
     * 
     * 这是任务执行器的核心方法，负责执行具体的任务逻辑。
     * 
     * 实现注意事项：
     * 1. 方法应该是线程安全的，因为可能被多个线程同时调用
     * 2. 应该正确处理传入的参数
     * 3. 应该捕获并处理异常，避免异常传播导致任务执行器崩溃
     * 4. 应该返回有意义的执行结果
     * 
     * @param jobExecutorParamsDTO 任务参数，包含任务执行所需的所有信息
     * @return 任务执行结果，包含执行状态和结果信息
     */
    JobExecutorResultDTO execute(JobExecutorParamsDTO jobExecutorParamsDTO);
}
